/*
 * @(#)LinkDb.java	0.1 01/01/04
 *
 * Copyright 2004 Fabio Gasparetti. All rights reserved.
 */
package org.tabularium.net.linkdb;

import java.util.Date;
import java.util.List;
import java.util.Collection;

/**
 * Provides the interface used to implement a storage of link sets.
 * <p>
 * The implementations should ensure that duplicate links will not be allowed.
 * 
 * @author Fabio Gasparetti
 * @version 0.1, 01/01/06
 */

public interface LinkDb {
	/*
	 * @todo Anti-duplication system: draw a MD5 for each page and store it in a
	 * table along the url. When someone asks for the inlinks or outlinks,
	 * retrieve all the urls matching the MD5 and consider them as a single
	 * resource.
	 */

	/**
	 * Returns the links' url that point to the given page.
	 * <p>
	 * The list is composed of String objects.
	 */
	public List inLinks(String url) throws LinkDbException;

	/**
	 * Returns the links' url that point to the given page.
	 * <p>
	 * The list is composed of String objects.
	 */
	public List inLinksOrderedByTimestamp(String url) throws LinkDbException;

	/**
	 * Returns the links' url contained in the given page.
	 * <p>
	 * The list is composed of String objects.
	 */
	public List outLinks(String url) throws LinkDbException;

	/**
	 * Returns the links' url contained in the given page.
	 * <p>
	 * The list is composed of String objects.
	 */
	public List outLinksOrderedByTimestamp(String url) throws LinkDbException;

	/**
	 * Adds a link to the db.
	 * <p>
	 * The first parameter is the url of the page that contains the
	 * <code>link</code>.
	 * Note: for duplicate link insertions, the implementation should specify its behaviour.
	 */
	public void addLink(String url, String link) throws LinkDbException;

	/**
	 * Adds a collection of links contained in the given page.
	 * <p>
	 * The first parameter is the url of the page that contains the collection
	 * of <code>links</code>.
	 * Note: for duplicate link insertions, the implementation should specify its behaviour.
	 */
	public void addLinks(String url, Collection links) throws LinkDbException;

	/**
	 * Adds a link to the db.
	 * <p>
	 * The first parameter is the url of the page that contains the
	 * <code>link</code>.
	 * Note: for duplicate link insertions, the implementation should specify its behaviour.
	 */
	public void addLink(String url, String link, Date ts) throws LinkDbException;

	/**
	 * Adds a collection of links contained in the given page.
	 * <p>
	 * The first parameter is the url of the page that contains the collection
	 * of <code>links</code>.
	 * Note: for duplicate link insertions, the implementation should specify its behaviour.
	 */
	public void addLinks(String url, Collection links, Date ts) throws LinkDbException;

	/**
	 * Removes a link from the db.
	 */
	public void removeLink(String url, String link) throws LinkDbException;

	/**
	 * Returns an iterator over the urls stored in the db. For each url it is
	 * possible to retrieve all the related links.
	 */
	public UrlIterator browse() throws LinkDbException;

	/**
	 * Clear the urls and links stored in the db.
	 */
	public void clear() throws LinkDbException;

	/**
	 * Returns the number of links stored in the db.
	 */
	public int size() throws LinkDbException;
}
